home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / util / disk / gcat452.lha / Gcat.doc < prev    next >
Text File  |  1995-07-03  |  17KB  |  379 lines
  1. Gcat:- a simple Amiga disk catalogger by John Marchant (aka "Gnome")
  2. ------
  3.               Version 45.20   18 June 95
  4.  
  5.   This program was developed as a project while learning C. It is still
  6. being developed as ideas come for improvements. My best ideas come 
  7. when I'm in my bath, on the toilet seat or gardening. To anyone who
  8. dislikes my spelling of "catalog", I say "Tough. I'm logging the disks
  9. and I like to call the result a catalog."
  10.  
  11. ***********************************************************************
  12.                ##### NOTICE #####
  13.   PLEASE NOTE that Gcat has not been idiot-proofed.
  14. There is no protection against making silly data entries in the
  15. Edit and Insert options.
  16. ***********************************************************************
  17.  
  18.   The program is Public Domain and must be accepted "as is".  NO WARRANTY
  19. is given that it is bug-free, and NO LIABILITY is accepted for any damage
  20. it may do to your hardware, your software or your peace of mind.  However I
  21. use it and I'm happy with it so far as it goes.  I'd call it "cheap and
  22. cheerful".
  23.  
  24.          --------------------------------------------------
  25.  
  26. The following files should be supplied with any copy of this program:-
  27.  
  28. GCat          The catalog program.
  29. CatHelp.txt   The online help text. Should be in the same directory as Gcat.
  30. req.library   Copy this into your libs: directory if you don't have it.
  31. testfile.cat  It's just a sample catalog to play with.
  32. Gcat.doc      The file you are reading. This file includes CatHelp.txt
  33. Gcat.guide    My first attempt at writing an Amigaguide
  34. ppmore        Utility for displaying help text. This should be in your
  35.                  c: or your sys:utilities directory.
  36.  
  37.          ---------------------------------------------------
  38.  
  39. Gcat may be started from the CLI or from Workbench.
  40.  
  41. If started from CLI with an argument c (i.e.  "Gcat c") an
  42. alternative color palette (grey, black, white, yellow) will be used.
  43. Otherwise the Workbench preference setting will be used.
  44.  
  45. If you start it by a CLI command, you should first change directory to the
  46. one in which your Gcat program and this help text are held. Otherwise the
  47. program will not be able to find the help text file, and will complain.
  48. So you should....
  49.  
  50.                cd <path to Gcat drawer>
  51.                run Gcat
  52.  
  53.   or of course you can use a wee startup script that does this for you, and
  54. you could execute this script using an alias. Or you could be clever and
  55. use IconX to execute the script.
  56.  
  57. If you start from the Workbench icon, there's no need to change directory.
  58.  
  59. There is a limit of 5000 set on how many files may be added to one Catalog.
  60. I'm not sure why, but there must be _some_ limit set, and 5000 seemed like
  61. a good idea! This may be revised later. (See also "Bugs" below.)
  62.  
  63.  ==== The following text is also in 'CatHelp.txt' for online viewing ====
  64.  
  65. The program is controlled by pulldown menus or hotkeys.
  66.  
  67. USING GCAT
  68. ============
  69.   To add data to your catalog you must first select the drive which will
  70.     be used for collecting data.
  71.   Then you simply insert disks into this drive and press RtAmiga/A each
  72.     time. The rest is automatic.
  73.   If you want to edit or delete an entry, point to it and click with the
  74.     left mouse button. The Edit window appears. Click on Edit or Delete, 
  75.     make any changes, and then click on Accept or Cancel.
  76.   You can also click & drag the pointer to select several lines, but the
  77.     dragging can't be used to de-select items already highlit. To do this
  78.     you must click on individual lines. The reason for this is to avoid
  79.     accidental deselection. (That's my excuse anyway.)
  80.   To insert an extra (new) entry, select the Insert menu option and follow
  81.     the instructions below.
  82.  
  83. The MENUS.
  84. ~~~~~~~~~~~
  85. Options menu
  86. =============
  87. SELECT INPUT DRIVE
  88.   This is the drive from which data will be read & added to the catalog.
  89.   e.g. If you select DF1: then all file names on DF1: will be added to
  90.     the catalog - ** even if they already exist in the catalog **
  91.   Only currently available drives will be offered.
  92.  
  93.   The drive you select here remains the drive used for gathering more data,
  94.     unless you select a new one from this menu option. It is unaffected by
  95.     the drive & file you may select to "Load Existing Cat" (though these
  96.     may be the same file & drive).
  97.  
  98. ADD DATA FROM DISK (RtAm/A)
  99.   This will cause the 'Input Drive' to be scanned, and all file names
  100.     (except those with .info extensions) will be appended to the current
  101.     catalog file in memory.
  102.  
  103.   The Catalog file will then be sorted & displayed without further menu
  104.     selection, and you can use the editing facilities described below under
  105.     'Load Existing Catalog'.
  106.  
  107.   You may then proceed to select further menu options, such as add
  108.     further data (from the selected "Input Drive"), change the current
  109.     input drive, or load an existing catalog.
  110.  
  111. SAVE FILE  (RtAm/S)
  112.     When you load an existing catalog file, or "add data from disk",
  113.   file names forming the catalog are read into memory. If any change is
  114.   made (edits, additions, deletions) you may wish to save the altered
  115.   catalog. If you ask to load a new catalog or quit without having
  116.   saved, a requester will remind you and ask if you wish to save.
  117.     If a catalog file name has not yet been specified, a requester
  118.   will appear for this purpose.
  119.  
  120. SAVE AS    (RtAm/N)
  121.     This is the same as SAVE FILE but asks you the name of the file you
  122.   wish to save to. e.g. you may wish to save it in a different place or
  123.   under a different name. (The 'N' hotkey represents "Name").
  124.  
  125. LOAD A CAT FILE    (RtAm/L)
  126.   This enables you to read an existing catalog. A requester will appear
  127.     for you to select the path and file.
  128.  
  129.   The file & drive you select here do not alter the current input drive.
  130.     If you want to add data to the catalog you select here and it's on
  131.     a different drive, you must use "Select Drive" to set the new
  132.     "current input drive".
  133.  
  134. START NEW CAT
  135.   Use this to clear the current catalog held in memory and begin a new
  136.     one. If changes have been made to a catalog currently held, you'll
  137.     be asked if you wish to save this first.
  138.  
  139. SELECT SORT
  140.   This produces a submenu with 2 options:
  141.     SORT ON FILENAME  (RtAm/1)
  142.     SORT ON DISKNAME  (RtAm/2)
  143.   These control the presentation of the list on screen. You can change
  144.     the sort at any time.
  145.  
  146. QUIT  (RtAm/Q)
  147.   This is a way to exit the program. You can also exit by using the window
  148.     close gadget. If a catalog is currently in memory & has not been saved
  149.     since it was last changed, a requester will appear to remind you.
  150.  
  151.             ------------------------------------------------
  152.  
  153. Insert Menu
  154. =============
  155.   INSERT ITEM  (RtAm/I)
  156.   ------------
  157.   Selecting this will bring up an 'Insert window' with several string
  158.     gadgets, and 2 button gadgets (OK and Cancel).
  159.  
  160.   There are 4 fields to be entered:
  161.        File Name    Path     File size (bytes)    Date
  162.   
  163.   See also "Edit window" below.
  164.  
  165.   Until the program is properly idiot-proofed, care should be taken to
  166.     enter data correctly. See the screen display for formats.
  167.   After making an entry and clicking on Accept, the new item is planted
  168.     in the file list, which is then re-sorted and displayed.
  169.  
  170.  
  171. Help Menu
  172. ==========
  173.   HELP  (RtAm/H or Help key)
  174.   -----
  175.   This will move the working screen to back and call ppmore to display
  176.   this text file you are reading. After use, the work screen returns.
  177.  
  178.   Please note that ppmore should be in your C directory, or some other dir
  179.     for which a path has been assigned for commands (e.g. Utilities).
  180.  
  181.  
  182. Printer Menu
  183. =============
  184.   PRINT CATALOG  (RtAm/P)
  185.   --------------
  186.   This formats and prints the catalog file currently displayed.
  187.     You should have your printer ready for action, as printing starts as
  188.     soon as you have made the request.
  189.  
  190.   WRITE TO FILE  (RtAm/W)
  191.   --------------
  192.   This will bring up a requester asking for the path & name of the output
  193.     file. The catalog currently being displayed will be formatted and written
  194.     to the selected output file. The Catalog data file is packed, with
  195.     many spaces removed, but 'Write to file' will format it as it appears
  196.     on the screen.  Unlike 'Print', there will be no page-breaks.
  197.  
  198.   SET PAGE LENGTH
  199.   ----------------
  200.   This allows you to change your print page length from the default 66 
  201.     lines to some other value (eg for A4 cut sheets). Two blank lines will
  202.     always be left at the foot of each page - ie 64 lines will be printed
  203.     on a 66 line page. Note that you cannot change the pagelength during the
  204.     printing.
  205.  
  206.   SET LETTER QUALITY
  207.   -------------------
  208.   Use this option if you want non 'draft' quality and your printer does
  209.     not have a high quality option switch on it. Setting this option
  210.     only changes the copy of your printer preferences currently held
  211.     in memory (and restores to its original setting after printing). 
  212.     It does NOT alter the setting of your Preferences held on disk.
  213.     If you already had 'Letter quality' set in your Preferences, this
  214.     option will make no difference.
  215.  
  216.     ----------------------------------------------------------------
  217.  
  218.   When a Catalog is displayed, you can scroll the text up and down, using
  219.     the proportional gadget or the arrow gadgets at right of screen. You
  220.     can also highlight lines by clicking on them with the left mouse button.
  221.     Selecting lines in this way causes the Selection buttons to appear.
  222.     
  223. The Selection buttons
  224. ----------------------
  225.   If you click on one or more lines on the screen, those lines are
  226.     highlighted and the selection buttons are revealed. 
  227.     Deletions & edits do not take effect until 'Accept' is selected.
  228.  
  229.   Delete:- if you click on this one, you are asking to delete all lines
  230.     you have selected whether or not they have scrolled off the screen.
  231.  
  232.   Edit:- brings up a 'string requester' containing the most recently 
  233.     marked line, and you can edit the line. Press OK to accept, or 
  234.     press Cancel. If more than one line was previously selected, only
  235.     the most recent one can be edited. Any others are unaffected.
  236.  
  237.   Accept:- accepts any changes into the catalog data.
  238.  
  239.   Cancel:- cancels the changes you have made and conceals the selection
  240.     buttons.
  241.  
  242.     ================== End of 'CatHelp.txt' =======================
  243.  
  244. The Catalog file (This section for enthusiasts only!)
  245. -----------------
  246.   This is a text file which may be edited if you wish.  A text editor can be
  247.     used: but be sure to retain the format, which has field separators as 
  248.     described below. (ie the lines are 'packed'.)
  249.  
  250.   Field 1 holds the file names in alphabetical order.
  251.  
  252.   Field 2 holds the disk name from which each file was extracted, and
  253.     the name of the lowest level of sub-directory in which it resides.
  254.     e.g. a file on df0:games/zaptype/Amoeba shows as
  255.                            Amoeba  df0:zaptype
  256.           This is only for reason of space in the line.
  257.  
  258.   Field 3 holds the file size in bytes, left-padded with spaces to 8 characters.
  259.  
  260.   Field 4 holds the date found on the file. If this is silly, then the
  261.     file has a silly date (or you entered it wrongly when editing).
  262.  
  263.   Fields are separated on the file by the vertical bar character |
  264.  
  265.   Until a "search" facility is added, the easiest way to search for a
  266.     file name is by using a text editor such as Cygnus Ed, or the DOS
  267.     "search" facility.
  268.  
  269.    ----------------------------------------------------------------
  270.  
  271. Recent History
  272. ================
  273. Vn 41 Revn 5: Option to use Workbench colours (by default), or my
  274.               own choice of colours (using 'c' argument).
  275.  
  276. Vn 42 Revn 0: The window and all gadgets now size themselves according
  277.               to the user's screen size. This cures problems with
  278.               overscan or non-standard screen heights.
  279.       Revn 1: Printing bug now corrected. Output text looped on
  280.               start of each page from page 3 onwards due to really
  281.               stupid coding error.
  282.       Revn 2: Inability to "see" drive Df2: now fixed.
  283.       Revn 3: Cosmetic tweaks of no consequence
  284.       Revn 4: Tiny bug fixed. It was possible to select a line one
  285.                below the bottom of the display window. Messy!
  286.       Revn 5: Menus disabled while in edit or insert mode. It was
  287.                found possible to ask for a sort while lines were
  288.                marked selected. This crashed the program.
  289.       Revn 6: Bug fix. It wasn't possible to select bottom line of scroll.
  290.               Input device submenu extended to include HD0,1,2,3
  291.  
  292. Vn 43 Revn 0: Cosmetic changes to menus, as requested by users.
  293.                 At LAST I've found out how to put only available
  294.                 disk devices into the drive selection sub-menu!
  295.                 It meant an extra program module, but was worth it.
  296.  
  297.       Revn 1: More cosmetic changes requested by pedantic friends :-)
  298.  
  299.       Revn 2: Bug fix: If the saved file path was long, Gcat crashed.
  300.       Revn 3: Cosmetic changes, & tidying of coding used in Revn.2
  301.  
  302. Vn 44 Revn 0: Hopefully the scrolling now behaves correctly and is not
  303.                 upset by different amounts of vertical screen overscan.
  304.       Revn 1: Bug preventing bottom 1 or 2 lines being selected: fixed.
  305.       Revn 2: Further problems fixed with scrolling on different screen
  306.               sizes. Is this problem finally fixed? Let's hope so.
  307.  
  308. Vn 45 Revn 0: At last I've figured out how to sort by file name within
  309.               disk name & path. This fulfils a long-time ambition :-)
  310.       Revn 1: Cosmetic improvement - Menus tidied
  311.       Revn 2: Menus disabled during reading disk or printing.
  312.  
  313. It was my intention to change to ASL requesters. The file requester is
  314.   easy, but a two-gadget input requester is very messy since ASL doesn't
  315.   support this and a further IDCMP channel has to be set up. Using
  316.   Req is far simpler, and in my opinion Req does a nicer file requester.
  317.  
  318. Further development is unlikely. This project has gone on far too long 
  319.   (about 3 years) and I'm bored with it. But I will still fix bugs.
  320.  
  321.          --------------------------------------------------
  322. BUGS?
  323. ------
  324. 1. If you ask to "Write to disk" a very large catalog (e.g. all of dh0:)
  325.   and try to put output to a file in ram: you can get a 'guru'. On a reset
  326.   & retry, the problem goes away. This is with plenty of free ram: so
  327.   maybe it's due to memory fragmentation?
  328.  
  329. 2.  Under low memory conditions the program may hang or crash with a
  330.   "MemoryInsane" alert. The program checks that memory is available while
  331.   reading in data, but certain activities such as sorting evidently need
  332.   more memory & you can run out. I've not met this in regular use with large
  333.   catalogs of 3 or 4 thousand files, but a tester has reported it. The problem
  334.   may be caused by memory fragmentation, so maybe a reset before running would
  335.   avoid it.
  336.  
  337. 3. In Vn 43.01 a small bug turned up when I had more than 11 disk type
  338.   devices available for data input. The "source drive" submenu didn't have
  339.   enough slots in it, and the parent menu was corrupted. You can now have
  340.   up to 15 possible input devices before any problem arises.
  341.  
  342.   The program has been tested on 68000, 68030 and 68040 processors, and with
  343. Enforcer. No hits were found.
  344.  
  345. User Problems
  346. ---------------
  347.   Bugs or nasties may be reported to me:-
  348.     a) Through fidonet: 2:2500/167.15
  349.              or usenet: gnome@martinac.demon.co.uk
  350.     b) By a message on my Bulletin Board "Moonlight" which is open most
  351.          nights 6pm - 8am.  Tel: +44 (0)1234 212752  (logon, fax or netmail).
  352.          1200 to 14400 baud, V32bis. Standard 8N1 protocol.
  353.     c) By snail mail at the address below.
  354.  
  355.   If possible please supply enough detail so that I can repeat what you
  356.     did to reproduce the bug you observed. Screen grabs are useful.
  357.  
  358. Credits
  359. =========
  360. Thanks to....
  361.  
  362.  Jim Perry of "Studio Services" for field-testing this program, and for
  363.     asking for the sort by disk-name. 
  364.  Bil Irving and Anthony Keeley for suggestions, advice & much winding me up.
  365.  Steve Parkinson for helping with programming problems & showing me how to
  366.     do the sort.
  367.  Chris Sumner for reporting some bugs I didn't know about.
  368.  Phillip Lindsay for the coding to list available disk devices - which I
  369.     discovered one day on Usenet.
  370.  Gavin Hamill for suggestions for improvement.
  371.  Mel Potter for testing, and screen-grabs showing the scroll problem.
  372.  Pink Floyd, Queen, and Nescafe Gold Blend for keeping me awake.
  373.  
  374. -----------------------------
  375. Version 45    June 1995
  376.  
  377. John Marchant,  43 Bowhill, Putnoe, Bedford MK41 8EQ,  UK.
  378. Fidonet:  2:2500/167.15   Internet: gnome@martinac.demon.co.uk
  379.